You are currently viewing the Homey Apps SDK v2 documentation. New apps should use Homey Apps SDK v3 ››

SDK Changelog

Homey v3.1.0

Homey v3.1.0 introduces Maintenance Actions for devices. This feature is only available to users running the Homey app v3.0.1 or higher.

Homey v3.0.0

Homey v3.0.0 introduces Homey Energy. Developers should update their apps accordingly to be visible under the Energy tab in the Homey app.

Device now has new methods Device.addCapability(), Device.removeCapability(), Device.setCapabilityOptions(), Device.setClass(), Device.getEnergy() and Device.setEnergy().

Homey v2.5.0

Homey v2.5.0 introduces Discovery, an easy way to find devices on the local network.

Homey v2.2.0

Homey v2.2.0 introduces a new Image API that is optimized for faster, efficient and more frequent use. The buffer-based api's have been deprecated in favor of Image.setStream and Image.getStream. Image formats are inferred and no longer need to be supplied with the creation of the image. This allows for images with changing formats.

It is possible to build apps with dual-compatibility. Continue to supply the format parameter to the image constructor, then use if(image.setStream) to check if the new API is available for use, and use the Image.setBuffer API otherwise.

Homey v2.0.0

Since Homey v2.0.0, the desktop interface has been removed in favor of the Homey app. You should verify that your apps still looks great in the new interface.

Devices are now capability-based

Previously, a device's class was dominant in deciding what a device could do, such as which Flow cards were rendered or how the mobile card looked like.

In Homey v2.0, a device's capabilities are leading and the device's class is now just a hint for some interfaces (e.g. speech).

Practically, this means that:

  • A device's Flow cards are generated based on a device's system capabilities
  • A device's speech commands are based on a device's system capabilities

Virtual Classes

A device's virtual class can now be changed in the device's settings. The choose_slave pair template is deprecated and will be skipped automatically.

Devices with the windowcoverings and socket device class, the user can now select a virtual class.

Removal of the Device.mobile property

The mobile property for a device that previously defined how the mobile card should look has been removed. A device's mobile interface is now automatically generated based on the device's capabilities and class.

System capabilities are rendered correctly automatically. Custom capabilities will default to a component fitted to their type, getable and setable properties. The component choice can be overwritten by a new property uiComponent.

Addition of the Driver.deprecated and FlowCard.deprecated property

A Driver and Flow card now accepts "deprecated": true in their manifest. This will not show the said Driver of Flow card for new users, but will keep working for existing users.

Web API

Usage of the Web API has been limited in apps with the homey:manager:api permission to the following scopes: homey.alarm homey.system.readonly homey.updates.readonly homey.geolocation.readonly homey.zone.readonly homey.device.readonly homey.device.control homey.flow.readonly homey.user.readonly homey.user.self homey.app.readonly homey.app.control homey.presence.readonly homey.insights.readonly homey.logic homey.speech.

Users wishing to use the Web API in their app must include athom-api v2.1 or higher in their app.

Custom Capabilities

  • A custom capability can now have an icon property, which is an absolute path to a .svg file. This icon is rendered in some UI components.

Promise-only APIs

ManagerBluetooth now returns only promises and callbacks aren't accepted anymore.

It is advised to update your code to use promises only for any API, because callbacks will be removed in a later SDK version.

Insights

Insights now work on a round-robin database style, which means that individual entries won't be logged but aggregated over time.

Practically this means that all your app's numeric Logs will have a minimum interval of 5 seconds.

Music

Homey Music has been removed in favor of the media component and the speaker_ capabilities.

Webviews

Webviews are now mobile-only. Libraries that Homey previously provided such as jQuery and Angular are deprecated and developers should include their own libraries.

Deprecation List

  • HD0001 - new Image(format), Image.format, Image.getFormat(), Image.getBuffer() and Image.setBuffer() are deprecated, please use Image.pipe() Image.setStream and Image.getStream